---

This section details on the original issue you should resolve

<issue_title>[Code Quality] Standardize validation errors to use structured error types</issue_title>
<issue_description>## Description

Convert validation errors across the codebase from plain fmt.Errorf to structured error types (ValidationError, ConfigurationError, OperationError). Currently, only 1% of validation errors include actionable suggestions despite having infrastructure in place.

Problem

Despite having well-designed error types with Suggestion fields, most validation errors use plain fmt.Errorf instead:

// Current pattern (no suggestions, no structure)
return fmt.Errorf("invalid mount at index %d: mode must be 'ro' or 'rw', got '%s'", i, mode)

// Should be (structured with suggestions)
return NewValidationError(
    fmt.Sprintf("sandbox.mounts[%d].mode", i),
    mode,
    "mount mode must be 'ro' (read-only) or 'rw' (read-write)",
    "Change the mount mode to either 'ro' or 'rw'. Example:\nsandbox:\n  mounts:\n    - \"/host/path:/container/path:ro\"",
)

Impact

• Severity: High
• Current State: Only 1 out of 88 ValidationError usages (1%) provide explicit suggestions
• User Impact: Users receive errors describing what's wrong but not how to fix it
• Files Affected: 83 validation files in pkg/workflow/

Files to Prioritize

1. pkg/workflow/sandbox_validation.go (many plain fmt.Errorf calls)
2. pkg/workflow/safe_outputs_domains_validation.go
3. All remaining *validation*.go files in pkg/workflow/

Suggested Changes

For each validation error using fmt.Errorf, convert to appropriate structured error type:

1. Field-level validation: Use NewValidationError(field, value, reason, suggestion)
2. Configuration errors: Use NewConfigurationError(configKey, value, reason, suggestion)
3. Operation failures: Use NewOperationError(operation, entityType, entityID, cause, suggestion)

Ensure every structured error includes:

• Clear reason explaining what's wrong
• Actionable suggestion for how to fix it (CRITICAL - currently only 1/88 errors have suggestions)
• Examples in the suggestion when helpful (especially for enum values, format requirements)

Success Criteria

• Identify all validation errors using plain fmt.Errorf in validation files
• Convert to appropriate structured error type
• Ensure all structured errors include actionable suggestions (target: >80% suggestion rate)
• Update error messages to include examples where helpful
• Maintain backward compatibility with existing error message content
• All tests pass after conversion
• Suggestion rate increases from 1% to >80%

Source

Extracted from Repository Quality Improvement: Validation Error Experience discussion githubnext/gh-aw#10683

Priority

High - Significantly improves user experience when debugging failed workflows

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 2, 2026, 2:08 PM UTC

Comments on the Issue (you are @copilot in this section)